Release 10.1A: OpenEdge Development:
Progress 4GL Reference

ASSIGN statement

Moves data previously placed in the screen buffer by a data input statement or moves data specified within the ASSIGN statement by an expression to the corresponding fields and variables in the record buffer.

Data movement

Syntax

ASSIGN { [ [ INPUT ] FRAME frame | BROWSE browse ] { field [ = expression ] } [ WHEN expression ] } ... [NO-ERROR]

ASSIGN { record [ EXCEPT field ... ] } [ NO-ERROR ]

[ FRAME frame | BROWSE browse ] field

The name of the field or variable (field) to be set from the corresponding value found in the screen buffer or expression. The field must be qualified by a frame name or browse name (frame) if field is specified as an input widget in more than one frame.

expression

An expression that results in an assigned value to the named field. In this case, Progress determines the field value from the expression rather than from the screen buffer.

WHEN expression

Moves data to the record buffer only when expression has a value of TRUE. Here, expression is a field name, variable name, or expression whose value is logical. Progress evaluates WHEN expressions at the beginning of the assignment, before any assignments take place.

NO-ERROR

Suppresses any errors that occur as a result of the operation. After the ASSIGN statement completes, you can check the ERROR-STATUS system handle for information about any errors that might have occurred.

If you do not specify this option and an error occurs, the assignment is canceled and any changes to field values within the assignment are undone. If the assignment occurs within a transaction, any changes to variables, work table fields, and temporary table fields are also undone, unless you define the variable or field with the NO-UNDO option.

record

The record buffer name with the fields set, from the corresponding values in the screen buffer. Naming a record is a shorthand way to list each field in that record individually.

To use ASSIGN with a record in a file defined for multiple databases, you might have to qualify the record’s filename with the database name. See the Record phrase reference entry for more information.

EXCEPT field

All fields in the record buffer are affected except for those listed. Separate field names with a space.

Examples

The following procedure prompts you for a customer number and retrieves the customer record if one exists, or creates a new one if it does not exist. If it creates a new record, the value for the cust-num field is ASSIGNed from the value you entered in response to the PROMPT–FOR statement.

r-asgn.p

REPEAT: PROMPT-FOR customer.cust-num. FIND customer USING cust-num NO-ERROR. IF NOT AVAILABLE customer THEN DO: CREATE customer. ASSIGN cust-num. END. UPDATE customer WITH 2 COLUMNS. END.

The next procedure changes the order number and line number of an order-line record. (It copies an order-line from one order to another.) It sets the new values into variables and modifies the record with a single ASSIGN statement that contains two assignment phrases in the form field = expression. Thus, both fields are changed within a single statement. Because Progress re-indexes records at the end of any statement that changes an index field value, and because order-num and line-num are used jointly in one index, this technique does not generate an index until both values change.

r-asgn2.p

DEFINE VARIABLE neword LIKE order-line.order-num LABEL "New Order". DEFINE VARIABLE newordli LIKE order-line.line-num LABEL "New Order Line". REPEAT: PROMPT-FOR order-line.order-num line-num. FIND order-line USING order-line.order-num AND line-num. SET neword newordli. FIND order WHERE order.order-num = neword. ASSIGN order-line.order-num = neword order-line.line-num = newordli. END.

Notes

If any field is a field in a database record, the ASSIGN statement upgrades the record lock condition to EXCLUSIVE–LOCK before updating the record.
If any field is part of a record retrieved with a field list, the ASSIGN statement rereads the complete record before updating it.
During data entry, a validation expression defined for the field in the database or in a Format phrase executes only if the widget associated with the field receives input focus. Use the VALIDATE( ) method to execute a validation expression defined for a field regardless of whether it receives input focus or not.
Use an ASSIGN statement after a PROMPT–FOR statement or to write changes from an enabled field to the database. ASSIGN moves the value from the screen buffer into the field or variable.
Use the PROMPT–FOR statement to receive one or more index fields from the user, and you use the FIND statement to find a record matching those index values. If no record is found, use the CREATE statement to create a new record and use the ASSIGN statement to assign the values the user supplied to the new record.
You cannot use the SET statement in place of the PROMPT–FOR statement. The SET statement prompts the user for input and then assigns that input to the record in the buffer. However, if there is not a record available, SET cannot assign the values.
ASSIGN does not move data into a field or variable if there is no data in the corresponding screen field. There is data in a screen field if a DISPLAY of the field was done or if data was entered into the field. If you PROMPT–FOR a field or variable that has not been DISPLAYed in the frame and enter blanks, Progress does not change the field or variable because it considers the screen field changed only if the data differs from what was in the field.
If an ASSIGN statement references a field or variable that is used in more than one frame, it uses the value in the frame most recently introduced in the procedure.
If you type blanks into a field that has never displayed data, the ENTERED function returns FALSE and the SET or ASSIGN statement does not update the underlying field or variable. Also, if Progress marks a field as entered, and the PROMPT–FOR statement prompts for the field again and you do not enter any data, Progress no longer considers the field entered.
If you use a single, qualified identifier with the ASSIGN statement, the Compiler interprets the reference as dbname.filename. If the Compiler cannot resolve the reference as dbname.filename, it tries to resolve it as filename.fieldname.
Many assignments within a single ASSIGN statement are more efficient than multiple ASSIGN statements. It saves r-code size and improves performance.
The ASSIGN statement, when used in database fields, causes all related database ASSIGN triggers to execute in the order in which the fields were assigned. The ASSIGN triggers execute after all the assignments have taken place. If an ASSIGN trigger fails (or executes a RETURN statement with the ERROR option), all of the database changes are undone. See OpenEdge Development: Progress 4GL Handbook for more information on database triggers.
You can assign DATE, DATETIME, and DATETIME-TZ data. When the data type expression on the left side of the assignment statement contains more information than the data type expression on the right side provides (for example, datetime-tz = date where a DATETIME-TZ value contains more information than a DATE value), the time value defaults to midnight and the time zone value defaults to the session's time zone. When the data type expression on the left side of the assignment statement contains less information than the data type expression on the right side provides (for example,
date = datetime-tz where a DATE value contains less information than a DATETIME-TZ value), Progress converts the DATETIME-TZ value to the local date and time of the session, then drops the time and time zone.
You can assign large object data from one BLOB or MEMPTR to another, and from one CLOB, LONGCHAR, or CHARACTER to another. You cannot assign large object data between BLOBs and CLOBs or MEMPTRs and LONGCHARs. You can accomplish, indirectly, by using the COPY-LOB statement. For more information, see the COPY-LOB statement reference entry.

Table 9 lists the default character conversions Progress performs when assigning CLOB, LONGCHAR, and CHARACTER data. References to CLOBCP and CLOBDB represent CLOB data in either the CLOB’s defined code page or the database's defined code page, respectively. References to the "fixed code page" represent the code page of a target LONGCHAR variable set using the FIX-CODEPAGE function.

Table 9: Default character conversions with the ASSIGN statement 

When the target field is a ...	And the source expression results in a ...	Progress converts the result of the source expression to ...
LONGCHAR	CLOBDB	-cpinternal or the fixed code page.
LONGCHAR	CLOBCP	The CLOB’s defined code page or the fixed code page.
LONGCHAR	CHARACTER	-cpinternal or the fixed code page.
CLOBDB	CHARACTER	The database's defined code page.
CLOBDB	LONGCHAR	The database's defined code page.
CLOBCP	CHARACTER	The CLOB’s defined code page.
CLOBCP	LONGCHAR	The CLOB’s defined code page.
CHARACTER	CLOBDB	-cpinternal code page.
CHARACTER	CLOBCP	-cpinternal code page.
CHARACTER	LONGCHAR	-cpinternal code page.

When you assign the Unknown value (?) to a BLOB or CLOB field, Progress deletes any associated object data.

See also

= Assignment operator, COPY-LOB statement, INPUT function, PROMPT-FOR statement, SET statement, UPDATE statement